Thank you for taking the trouble to try this program out. We hope you like it.
Note: this file is formatted and is best read with SimpleText and not TeachText.
Note: this file is not read-only so that you can easily copy the text if you want to. For example, you can copy the email addresses and URLs. Please donﾕt modify this file or distribute modified versions.
Note: you should scroll up and down a pageful at a time so that the pictures will appear properly. If the pictures donﾕt appear, you can make them appear by scrolling up a page and then back down a page.
This software is copyrighted material and therefore you are not allowed to modify this software or its documentation in any way, shape or form, nor can you sell it for your own profit. You may only charge a reasonable fee for the cost of distributing it. See the Distribution section below for information about how and on what IIe may be distributed.
Contents
The documentation for IIe comes in 4 files. Their contents are:
1. Read me first
What is it? - description, features, requirements, compatibilty, and performance issues
Description
Features
Hardware and software requirements
Compatibility
Performance issues
Installation and setup
Simple installation/setup
Tips
Frequently Asked Questions (FAQ)
2. Instructions
The Apple //e window
The display area
The //e screen
The icon buttons
Function keys
Graphics modes
Disk inserting/removing
Using real disks
Using disk images
How to insert and remove disks and disk images
Loading and saving information - memory images
Emulator instructions
Default settings
Starting up the emulator
The Reset key
The Keyboard
Paddles and buttons
Debugger instructions
3. Configuring IIe
General pane
65c02 pane
Memory pane
Video pane
Sound pane
Keyboard pane
Input devices pane
Disks pane
Slots pane
4. Other stuff
Cost/fee and registration
Version history
Future version features
Distribution
Contacting the author
Other software by Vincent
Disclaimer
2. Instructions
Itﾕs assumed that you know how to use an Apple II computer. That is, youﾕre aware of how to switch it on, insert a disk, boot a disk, remove a disk, use the keyboard and use the joystick. If you know these things then youﾕll find using IIe virtually the same as using an Apple //e except that the disk ﾒinsertionﾓ and ﾒremovalﾓ activities are virtual instead of real (unless you insert a real floppy disk into your Mac in which case itﾕs real - hmmm, are you confused yet?).
If you donﾕt know how to use an Apple II, just try using IIe anyway, but please donﾕt send e-mail asking for this kind of help. Instead, trying posting a message to an Apple II message board. Be polite and explain your ignorance of the Apple II. There should be some kind soul to help you out. If youﾕre on the internet, try the USENET newsgroups such as ﾔcomp.sys.apple2.<something>ﾕ or ﾔcomp.emulators.apple2ﾕ.
The following instructions pertain only to features specific to this emulator.
The Apple //e window
ﾊ
This window is divided into several areas:
The display area
At the top is the status display area. It shows you the disk drive lights and which slot/drive they belong to and what image files you have loaded into them. To insert or remove a disk, you can click the Insertﾉ and Removeﾉ icons on the right side of the window. With more cards installed in the //e, you will see more icons and names in this area (2 for the UniDisk/Hard Disk card, 1 for the memory card, 1 for the MacProDOS card). At the bottom right of the status area is the Soft caps lock status line. You can activate the Soft caps lock feature from the IIe Preferences window (see the document ﾒ3. Configuring IIeﾓ for instructions on how to do this).
The //e screen
At the bottom left, of course, is the //eﾕs display area which does the function of a real //eﾕs video monitor. You cannot select anything in this area but you can copy the contents of the //e screen to the Mac clipboard from the Edit menu.
The icon buttons
At the bottom right are eight useful icons to make it easier for you to use IIe. They are:
･ ﾒInsertﾉ F5ﾓ lets you select disk images, memory images, and folders for use in a //e drive
･ ﾒRemoveﾉ F6ﾓ lets you remove a disk image from a //e drive. Note that if you insert a disk image into a drive that already has a disk image in it, the old image is closed first.
･ ﾒResetﾓ simulates a press of the //eﾕs reset key (you can also achieve the same effect by pressing control-delete on your Mac keyboard). This icon is disabled is the //e is off or not running).
･ ﾒGo F15ﾓ or ﾒStop F15ﾓ starts and stops the //e (freezes and runs it). This icon can also function as an on/off switch such that clicking it would be the same as turning off a real //e. When configured in this manner, it will be displayed as ﾒOn F15ﾓ and ﾒOff F15ﾓ. See the ﾒ3. Configuring IIeﾓ for instructions on how to configure it to do this.
･ ﾒPrefsﾉ F7ﾓ opens the IIe Preferences window. If it has not been previously opened, it is opened at the top-most pane, otherwise it is opened at the most recent pane.
･ ﾒSlotsﾉﾓ opens the IIe Preferences window at the Slots pane to let you change the slots. However, changing the slots will not take effect until you quit IIe and start it up again.
･ ﾒMono F13ﾓ and ﾒColour F13ﾓ changes the screen display from monochrome to colour and vice versa. You can also option-click the icon to change depths from 8 -> 1 bit depth, 1 -> 4 bit depth, and 4 -> 8 bit depth. You can also control-click it to change the display: if youﾕre in monochrome mode, it changes the monochrome-white colour from white -> green, green -> amber, amber -> white; if youﾕre in colour mode, it does nothing except in double hires mode in which case it will display a sharpened image (but this mode is slower than the normal unsharpened image).
･ ﾒInterruptﾓ halts the emulation at whatever instruction it is currently at and displays that in the debugger window. Donﾕt use this icon unless you really need to, or unless you know what you are doing. Why use it? Well itﾕs handy if you know 65c02 assembly and want to see what the processor is doing. Eg, ﾒis it hanging or still reading the disk? I know! Iﾕll check by interrupting it!ﾓ Warning: the debugger window is still in development and as such is still very much ﾒrawﾓ in its functioning.
Function keys
If you have an extended keyboard, you can also use the F-keys at the top of the keyboard. There are 15 such keys, numbered 1 to 15. Their functions are:
･ F3: this is the same as selecting ﾒCopyﾓ from the Edit menu. It will copy the //e screen to the clipboard (including text if in text mode).
･ F5: this is the same as selecting ﾒInsert Diskﾉﾓ from the File menu or clicking the ﾒInsertﾉﾓ icon.
･ F6: this is the same as selecting ﾒRemove Diskﾉﾓ from the File menu or clicking the ﾒRemoveﾉﾓ icon.
･ F7: this is the same as selecting ﾒPreferencesﾉﾓ from the File menu or clicking the ﾒPrefsﾉﾓ icon.
･ F8: this is the same as selecting ﾒSave IIe Imageﾉﾓ from the File menu.
･ F9: step over instruction (active only when the debugger window is active).
･ F10: step into instruction (active only when the debugger window is active).
･ F11: step out of instruction (active only when the debugger window is active).
･ F12: if the debugger window is not active (the emulator is running and is not being debugged) then this key will interrupt the emulator and control is handed to the debugger - it functions as if you had clicked the Interrupt button. If however the debugger window is active, then F8 will function as if you had clicked the Run button in the debugger window. The overall effect is to alternatively interrupt and execute the CPU.
･ F13: this is the same as selecting ﾒMono/Colourﾉﾓ from the File menu or clicking the ﾒMono/colourﾉﾓ icon. You can also use the option and control keys to select extra options (see Graphics modes below)
･ F15: this is the same as clicking the ﾒpower switchﾓ icon. Depending on what option the power switch is set to, it will either halt/run the emulator or power-on/power-off the emulator.
Graphics modes
･ IIe shows you the //eﾕs screen in a Mac window. This window should always be located on the same screen as your menu bar. If you have more than one monitor connected, please do not drag the window to a different monitor because IIe does not support multiple monitors.
･ normal 40 column text, 40 column lores and ﾒnormalﾓ hires graphics can be displayed in either a small 280 * 192 area or in a larger 560 * 384 area. You can alternate between the two sizes by clicking the windowﾕs zoom box.
･ 80 column text, 80 column lores and double hires graphics must be displayed in the large 560 * 384 window. You cannot switch to a smaller display whilst any of these modes are active, and activating any of these modes (such as ﾒPR#3 [return]ﾓ from BASIC) will make the emulator switch to the larger size.
･ clicking the mono/colour icon button changes the display of hires graphics and double hires graphics from monochrome to colour and vice versa. It does not affect text or lores graphics. Naturally, this button does nothing if your Macﾕs monitor is set to display black-and-white (1 bit depth).
･ clicking the mono/colour icon button whilst holding down the option key changes the depth of the Mac monitor. The depth is rotated from 256 colours (8-bit) to black-and-white (1-bit) to 16 colours (4-bit) and then back to 256 colours (8-bit).
･ clicking the mono/colour icon button whilst holding down the control key changes the colour of the monochrome colour. Text is displayed in this colour and so will be affected, as will hires graphics and double hires graphics if the display is set to monochrome (by clicking the mono/colour icon button by itself). Note: control-clicking the icon does nothing if your Macﾕs monitor is set to display black-and-white (1 bit depth).
Disk inserting/removing
You can insert different kinds of disks into IIeﾕs ﾒdrivesﾓ. They can be real 3 1/2" disks, real ProDOS SCSI hard disk partitions, or disk images - a (Mac) file that ﾒcontainsﾓ an Apple II ﾒdiskﾓ.
Using real disks
Inserting a real 3 1/2" disk
To use a real 3 1/2" disk, run IIe and when the ﾒApple //eﾓ window is the front window, insert your 3 1/2" disk into any Mac drive. You will be asked if you wish to ﾒinsertﾓ the disk into a ﾒdriveﾓ, and if so, to select which ﾒdriveﾓ to insert it into. Select your drive and youﾕre set to use that disk.
Note that although you can insert a Mac formatted disk into the disk drive and then have IIe ﾒinsertﾓ it into one of its drives, it wonﾕt be very useful. For all practical purposes, you should insert a ProDOS formatted disk into IIeﾕs drive (see below for info about ProDOS). If you wish to transfer ProDOS files that are on a Mac floppy disk for use in IIe, you should use the ﾒMacProDOS diskﾓ peripheral which allows you to transfer files on a Mac disk or folder directly into ProDOS running on the //e.
Inserting a real ProDOS SCSI hard disk partition
To use a real disk, run IIe. If you have configured a UniDisk into one of the //eﾕs slots and you have a real ProDOS SCSI hard disk partition on your hard disk, you will usually be asked if you wish to ﾒinsertﾓ that ProDOS SCSI hard disk partition into a ﾒdriveﾓ, and if so, to select which ﾒdriveﾓ to insert it into. Select your drive and youﾕre set to use that disk.
Using disk images
Introduction
To use a disk image, you need to prepare the file properly before you can ﾒinsertﾓ it into a IIe ﾒdriveﾓ. A short description of why this is necessary and how to do this follows.
On the Apple II, there are 2 main file systems: DOS 3.3, an older format (and probably the more commoner of the two) which usually supports only 5 1/4" disks; and ProDOS, the newer system which supports different sized disks. The order and format of data on these two systems are completely different from each other, and therefore disk images of disks in these systems are completely different in order and format from each other. As well, there is another file system called Apple Pascal, but isnﾕt used much (Wizardry is probably the most famous program that used it).
5 1/4" disk images
Most of the disk images of 5 1/4" disks that are available on the internet are in ﾒDOS 3.3ﾓ order and are stored as plain compressed (usually gzipped) binary files. They usually have a ﾒ.dskﾓ suffix and are usually 143360 bytes when decompressed. So a typical file is stored as ﾔcoolgame.dsk.gzﾕ. This is for the benefit of PC users. When you download such a file to your Mac and decompress it, the file is usually of the wrong Macintosh file type and creator (for example, StuffIt Expander decompresses such files to SimpleText text files: type ﾔTEXTﾕ, creator ﾔttxtﾕ). To use the disk image file with IIe, you need to change the type to one that IIe can use. The fileﾕs type should be changed to ﾔDSK5ﾕ and its creator to ﾔAIIeﾕ. When you do this, the file can be double clicked and then opened by IIe.
Dos 3.3 ordered 5 1/4" disk images can also have a suffix of ﾒ.doﾓ. Again, change their type/creator to ﾔDSK5ﾕ/ﾔAIIeﾕ.
The other possible formats for 5 1/4" disks are:
･ ﾒProDOSﾓ order, usually with a ﾒ.poﾓ or ﾒ.diskﾓ suffix. Like Dos 3.3 order disks, they are 143360 bytes long. Change their type/creators to ﾔDISKﾕ/ﾔAIIeﾕ for use in IIe, and
･ ﾒnibbleﾓ format. These images are usually 232960 bytes long. For example, another Apple II emulator for the Mac called ﾒStopTheMadnessﾓ saves to disk images only in ﾒnibbleﾓ format. To use them with IIe, change their type/creators to ﾔNIBBﾕ/ﾔAIIeﾕ.
3 1/2" disk images
Most of the 3 1/2" disk images are similar to the 5 1/4" disk images except that they are usually in ﾒProDOSﾓ order. Aside from that, they are usually stored as plain compressed (usually gzipped) binary files. Again, they usually have a ﾒ.dskﾓ suffix. Again, theyﾕll have the wrong Macintosh file type and creator. To use the disk image file with IIe, you need to change the type to ﾔDSK3ﾕ and its creator to ﾔAIIeﾕ. When you do this, the file can be double clicked and then opened by IIe.
For Mac users, a convenient format for 3 1/2" disks is the Apple Disk Copy format. This is the format that is created by disk imaging software such as Appleﾕs Disk Copy 4.2 or Chad Magendanzﾕs ShrinkWrap. Such disk images have ﾒProDOSﾓ ordering. This format is different to the ﾒplainﾓ 3 1/2" disk image that is usually found on the internet. Disk Copy images have an extra 84 bytes of data at the beginning of the image to identify the imageﾕs format. Disk images in this format have the file type ﾔdImgﾕ. This does not need to be changed for IIe to use them: you can drag and drop those files onto IIeﾕs icon. However, if you want to be able to double click the disk image and have IIe open it, youﾕll need to change itﾕs creator to ﾔAIIeﾕ. The nice thing about this format is that you can mount these files on your Mac desktop if you have ﾒProDOS File Systemﾓ or ﾒPC Exchangeﾓ installed: you drag and drop the image on top of ﾒShrinkWrapﾓ or ﾒDropDiskﾓ and it will mount on your desktop. You can modify the image if you mount if with ﾒShrinkWrapﾓ but not ﾒDropDiskﾓ.
Note that DiskCopy images that are modified by IIe can be written out to real 3 1/2" disks with DiskCopy - the checksums are updated when you remove the disk image from the drive or when you quit IIe.
Hard disk images
Finally, there are disks stored in hard disk volume format. They usually have a ﾒ.hdvﾓ suffix. They are ProDOS ordered files and are usually images of Apple II hard disks. They arenﾕt common but are supported nonetheless. They have a file type ﾔHDV ﾕ (note the space at the end). Change the fileﾕs creator to ﾔAIIeﾕ so you can double click them into IIe.
Changing file types and creators
To change a fileﾕs type or creator, use a file type editor such as ResEdit (free from Apple), BunchTyper (free), FileTyper (shareware), or Aladdinﾕs Desktop Tools (good quality commercial utility [biased opinion]).
How to insert and remove disks and disk images
After the disk image file is set up for use, you can drag it to IIe or just double click if itﾕs creator is set to ﾔAIIeﾕ. You can also select ﾒInsert Disk Imageﾉﾓ from the File menu or click the ﾒInsertﾉﾓ icon button. IIe will then ask you which //e slot and drive to insert the disk into. IIe supports two 5 1/4" drives and two 3 1/2" drives for each installed disk drive ﾒcardﾓ.
You can remove disks by selecting ﾒRemove Disk Imageﾉﾓ from the File menu or click the ﾒRemoveﾉﾓ icon button. In the dialog that appears, select which disks you want to remove and click Remove. Note that you do not need to remove a disk before inserting a new one; newly inserted disks displace disks that are already in that drive (that is, the old one is automatically removed for you).
Loading and saving information - memory images
The best way to load and save your data is by saving it to a disk or disk image, which is done by selecting the save command in the Apple II program. However, there are some programs that donﾕt let you save but there are times that you need to save what youﾕre doing and return to it later - for example, youﾕve spent the last 3 hours playing Lode Runner and you a wedding to go to. To solve this problem, IIe allows you to save its current state by the use of ﾒmemory imagesﾓ. In a nutshell, this operation takes a ﾒsnapshotﾓ of the //eﾕs memory and saves it on disk, where it can later be restored.
Note that the size of the saved image will be the size of the current //e memory including any extra auxilary memory you have allocated to the RamWorks III card. So if you have set up a //e with 1 Mb of auxilary memory, the saved image will be 64K (main memory) + 1024K (aux memory). IIe will not save the contents of any Memory Card you install in a slot however.
When you ask IIe to load a memory image, it first checks that the size of the saved image is the same as the current memory setup. If it is, it loads it in and restores the //e to the saved state. Of course, you lose whatever you had in the //eﾕs memory. You will not be warned of this loss because IIe assumes you know what youﾕre doing when you open the memory image. If the memory imageﾕs size does not match the current memory setup, then IIe will offer to load in only the first 128K or to cancel the load operation, and it will tell you what you need to set the memory size to if you want to load the whole image.
Emulator instructions
This section covers topics related to the use of the emulator and its peripherals.
Default settings
The default settings for IIe are:
･ small screen
･ no change in depth
･ colour mode
･ does not draw directly to your screen
･ 1MHz speed
･ 64K only of auxillary memory
･ produces soft sounds
･ no ﾔdeleteﾕ key translation
･ no type-ahead buffer
･ soft caps lock disabled
･ joystick emulation via the keypad
･ fast disk reads and writes
･ ask what to do if a ProDOS hard disk is found
･ the default Mac-ProDOS folder is the folder that the IIe program is in
･ Disk II in slot 6 (fixed)
･ 80 column card in slot 3 (fixed)
･ no other cards installed
Starting up the emulator
If you start IIe with a disk (by double clicking the disk imageﾕs icon or by dragging it to IIeﾕs program icon), the emulator will start running as soon as it is ready and the disk is ﾒinsertedﾓ.
However, when you start IIe without any disks in any drive, the emulator wonﾕt run until you tell it to. You can start it up by clicking the ﾒRun/Stopﾓ icon button. Pressing it again will stop it. Alternatively, you can press F15. The icon will change to show you the state of the emulator. Of course, it isnﾕt very useful without a diskﾉ
Bonus: if you start IIe up with the command key held down, then IIe will use the title of the //e window to show you how many 65c02 clock cycles it has emulated in each of its emulation cycles (which are about half a second long).
The Reset key
To ﾒresetﾓ the //e, that is, simulate the pressing of the reset key on a real //e, press control-delete (the delete key here acting like the reset key) or the ﾒResetﾓ icon button. Tip: to force a ﾒcoldﾓ reboot, press command-control-delete or command-click the ﾒResetﾓ icon button. If you want to see the //e diagnostic test, press option-control-delete (or option-click the ﾒResetﾓ icon button) (but the test is kind of boring in my opinionﾉ)
The Keyboard
When the emulator is running, all keystrokes are directed to the //e window. When the emulator is not running, all keystrokes are directed to the IIe program, that is, the menu bar or the frontmost window. So if you press command-I to insert a new disk and nothing happens, be sure that the emulator is not running. If it is running, press control-esc or F15 or the ﾒRun/Stopﾓ icon button, to first halt it and then press command-I (or just click the ﾒInsertﾉﾓ icon button if you donﾕt want to stop the emulator).
The ﾔdeleteﾕ key on the Mac keyboard can be configured to produce either a ﾔbackspaceﾕ or a ﾔdeleteﾕ key on the //e.
IIe implements a type-ahead buffer so you wonﾕt lose keystrokes but some programs (especially games) donﾕt respond with this on so you may have to turn it off. For text editors and word processors, youﾕll probably want to turn it on.
The Tab key can be configured as a ﾔsoft caps lockﾕ key. If configured as such, then when you first press it, it changes any key you type from uppercase to lowercase and vice versa. When pressed again, it does not change the keys. In other words, it acts just like the real ﾔcaps lockﾕ key but the changes apply only to //e. This allows you to keep the real ﾔcaps lockﾕ key in your preferred position without having to change it every time you use another Mac program.
Paddles and buttons
The paddles/joystick is emulated by the use of either the Mac keypad or the mouse. If you have a joystick or gamepad attached to your Mac, you should set it to simulate the keypad.
If the keypad is selected to emulate the joystick, then:
･ Keypad 7 is the same as pushing the joystick to the top-left
･ Keypad 3 is the same as pushing it to the bottom-right
･ Keypad 1 pushes it to the bottom-left
･ Keypad 9 pushes it to the top-right
･ The other keypad keys push it in between the corners
Iﾕve found that this arrangements works quite well - most programs Iﾕve tried it with have no problems with it.
If the mouse is selected to emulate the joystick, then moving the mouse around the screen will move the joystick in the same direction. You can configure the mouse paddle values to be based on the mouseﾕs screen position or its position within the //e window.
This emulator uses a ﾒsmartﾓ paddle emalation routine (technical weenies: it counts clock cycles), so all paddle/joystick reading programs should work. If you find a program that doesnﾕt work well, let me know and Iﾕll investigate it.
The ﾒopenﾓ and ﾒclosedﾓ apple keys on the //e keyboard (paddle 0ﾕs button and paddle 1ﾕs button respectively), as well as the third paddle button are supported. The Mac keys to use are command, option and shift respectively.
Debugger instructions
Important: most people will not need to read this section for ordinary use of IIe. This section covers the use of the debugger which is a tool for seeing what the //e is doing at the machine instruction level.
If you end up in the debugger and donﾕt know what to do, try clicking the Run button. If it fails, try clicking the Reset button. If that fails, youﾕll have to power down the //e or quit IIe and restart it.
Currently the debugger is in a ﾒrawﾓ state, ie, incomplete and rough at the edges. However, you can use it to do some interesting things such as:
･ set a breakpoint
･ step an instruction
･ step over an instruction
･ step over all instructions in a loop and stop at the end of a loop
･ step over all instructions in a 65c02 subroutine and stop at the point after the caller routine called the subroutine
･ break on interrupts
･ reset the //e
･ run the //e
･ disassemble memory
･ change memory and the 65c02 registers
Oops. Iﾕll get around to writing this section for the next release. Letﾕs say that learning about the debugger ﾒis left as an exercise for the readerﾓ :-)
